Inside Macintosh: Sound

Releasing Sound Channels

To dispose of a sound channel that you have allocated with SndNewChannel , use the SndDisposeChannel function. SndDisposeChannel requires two parameters, a pointer to the channel that is to be disposed and a Boolean value that indicates whether the channel should be flushed before disposal. Here's an example:



 
myErr := SndDisposeChannel(mySndChan, TRUE);

Because the second parameter is TRUE , the Sound Manager sends both a flushCmd command and a quietCmd command to the sound channel (using SndDoImmediate ). This removes all commands from the sound channel and stops any sound already in progress. Then the Sound Manager disposes of the channel.

If the second parameter is FALSE , the Sound Manager simply queues a quietCmd command (using SndDoCommand ) and waits until quietCmd is received by the channel before disposing of the channel. In this case, the SndDisposeChannel function does not return until the channel has finished processing commands and the queue is empty.

If you dispose of a channel currently playing from disk, then your completion routine will still execute, but will receive a pointer to a sound channel that no longer exists. Thus, you should stop a play from disk before disposing of a channel. See "Managing an Asynchronous Play From Disk" for more information on completion routines.

Although the SndDisposeChannel function always releases memory reserved for sound commands, SndDisposeChannel cannot release memory associated with a sound channel record if you have allocated that memory yourself. For example, if you use the MyCreateSndChannel function defined in Listing 1-11 to create a sound channel, you must dispose first of the sound channel and then of the memory occupied by the sound channel record, as illustrated in Listing 1-13 .

Listing 13 Disposing of memory associated with a sound channel



 
FUNCTION MyDisposeSndChannel (sndChan: SndChannelPtr; quietNow: Boolean): 

                                            OSErr;

VAR

    myErr:      OSErr;

BEGIN

    myErr := SndDisposeChannel(sndChan, quietNow);                  {dispose of channel}

    DisposePtr(Ptr(sndChan));                                       {dispose of channel ptr}

    MyDisposeSndChannel := myErr;

END;

If you have played a sound resource through a channel, the SndDisposeChannel function does not free the memory taken by the resource. You must call the Resource Manager's ReleaseResource function to do so, or, if you have detached a resource from a resource file, you could free the memory by making the handle unlocked and purgeable. Note that if you play a sound resource asynchronously, you should not release the memory occupied by the resource until the sound finishes playing or the sound might not play properly. For information on releasing a sound resource after playing a sound asynchronously, see "Playing Sounds Asynchronously" .

In Sound Manager versions 3.0 and later, you can play sounds in any number of sound channels. In earlier Sound Manager versions, however, only one kind of sound can be played at one time. This results in several important restrictions on your application. In Sound Manager version 2 and earlier, you should create sound channels just before playing sounds. Once the sound is completed, you should dispose of the channel. If your application is switched out and does not release a sound channel, then other applications may be unable to open sound channels. In particular, the system alert sound might not be heard and the user might not be notified of important system occurrences. In general, while it is acceptable to issue a number of sound commands to the same sound channel, it's not a good idea to play more than one sampled sound on the same sound channel.